/**
 * 固定时间步长管理器（带插值渲染）
 * 
 * 职责：
 * 1. 确保逻辑系统以固定帧率运行（如 20 FPS）
 * 2. 渲染系统以显示帧率运行（如 60 FPS）
 * 3. 提供插值因子用于平滑渲染
 * 4. 防止死亡螺旋（时间累积过多）
 * 
 * 工作原理：
 * - 逻辑更新：固定时间步长（0.05秒 = 20 FPS）
 * - 渲染更新：每帧更新（~0.016秒 = 60 FPS）
 * - 插值：在两个逻辑帧之间平滑过渡
 * 
 * @author AI Assistant
 * @date 2025-11-26
 */

import { ecs } from "../../core/ecs/ECS";
import { Log } from "../../core/logger/LoggerGlobal";
import { DEBUG } from 'cc/env';

// 开发环境专用：统计管理器
// @if DEBUG
import { FixedUpdateStatsManager } from "./FixedUpdateManagerStats";
// @endif


/**
 * 固定更新管理器配置
 */
export interface FixedUpdateConfig {
    /** 逻辑帧率（FPS） */
    logicFPS?: number;
    
    /** 最大允许的单帧时间（秒），防止死亡螺旋 */
    maxDeltaTime?: number;
    
    /** 是否启用插值 */
    enableInterpolation?: boolean;
    
    /** 是否启用性能统计 */
    enableStats?: boolean;
}

/**
 * 固定更新管理器（使用依赖注入）
 * 
 * 职责：
 * 1. 管理固定时间步长更新
 * 2. 直接管理逻辑系统列表（不使用 ECSRootSystem）
 * 3. 提供插值因子给渲染系统
 * 4. 防止死亡螺旋
 */
export class FixedUpdateManager {
    // ========== 配置 ==========
    
    /** 固定时间步长（秒） */
    private fixedTimestep: number = 1 / 20; // 默认 20 FPS
    
    /** 最大允许的单帧时间（秒） */
    private maxDeltaTime: number = 0.25; // 250ms
    
    /** 是否启用插值 */
    private enableInterpolation: boolean = true;
    
    // ========== 运行时状态 ==========
    
    /** 时间累加器 */
    private accumulator: number = 0;
    
    /** 插值因子（0-1） */
    private interpolationAlpha: number = 0;
    
    /** 逻辑系统列表 */
    private logicSystems: Array<ecs.System | ecs.ComblockSystem> = [];
    
    /** 当前是否正在执行逻辑更新 */
    private isInLogicUpdate: boolean = false;
    
    // ========== 开发环境专用：统计管理器 ==========
    // @if DEBUG
    private statsManager: FixedUpdateStatsManager | null = null;
    // @endif
    
    constructor() {
        // @if DEBUG
        // 开发环境：创建统计管理器
        this.statsManager = new FixedUpdateStatsManager();
        Log.ecs.debug('FixedUpdateManager 已创建（开发环境）');
        // @endif
        
        // @if !DEBUG
        Log.ecs.debug('FixedUpdateManager 已创建（生产环境）');
        // @endif
    }
    
    /**
     * 配置管理器
     */
    configure(config: FixedUpdateConfig): void {
        if (config.logicFPS !== undefined) {
            this.fixedTimestep = 1 / config.logicFPS;
            Log.ecs.info('逻辑帧率设置', {
                fps: config.logicFPS,
                timestep: this.fixedTimestep.toFixed(4)
            });
        }
        
        if (config.maxDeltaTime !== undefined) {
            this.maxDeltaTime = config.maxDeltaTime;
        }
        
        if (config.enableInterpolation !== undefined) {
            this.enableInterpolation = config.enableInterpolation;
        }
        
        // @if DEBUG
        // enableStats 在生产环境被完全移除，无需配置
        // @endif
    }
    
    /**
     * 注册逻辑系统
     */
    registerLogicSystem(system: ecs.System | ecs.ComblockSystem): void {
        // 初始化系统并添加到列表
        if (system.hasOwnProperty('comblockSystems')) {
            // 这是一个 ECSSystem，需要摊平
            const ecsSystem = system as any;
            if (typeof ecsSystem.init === 'function') {
                ecsSystem.init();
            }
            // 将系统摊平
            if (Array.isArray(ecsSystem.comblockSystems)) {
                this.logicSystems.push(...ecsSystem.comblockSystems);
            }
        } else {
            // 这是一个 ComblockSystem
            const comblockSystem = system as any;
            if (typeof comblockSystem.init === 'function') {
                comblockSystem.init();
            }
            this.logicSystems.push(system);
        }
        
        Log.ecs.info('注册逻辑系统', { 
            systemName: system.constructor.name,
            totalCount: this.logicSystems.length
        });
    }
    
    /**
     * 获取逻辑系统数量
     */
    getLogicSystemCount(): number {
        return this.logicSystems.length;
    }
    
    /**
     * 主更新函数（每帧调用，约 60 FPS）
     * @param dt 距离上一帧的时间（秒）
     */
    update(dt: number): void {
        // @if DEBUG
        // 开发环境：计时开始
        const updateStartTime = this.statsManager?.getNow() || 0;
        this.statsManager?.recordRenderFrame();
        // @endif
        
        // 1. 限制最大时间步，防止死亡螺旋
        if (dt > this.maxDeltaTime) {
            Log.ecs.warn('帧时间过长，已限制', {
                actualMs: (dt * 1000).toFixed(2),
                limitMs: (this.maxDeltaTime * 1000).toFixed(2)
            });
            dt = this.maxDeltaTime;
            
            // @if DEBUG
            this.statsManager?.recordSkippedFrame();
            // @endif
        }
        
        // 2. 累加时间
        this.accumulator += dt;
        
        // 3. 固定时间步长更新（可能执行 0、1 或多次）
        let logicUpdateCount = 0;
        
        // @if DEBUG
        const logicStartTime = this.statsManager?.getNow() || 0;
        // @endif
        
        while (this.accumulator >= this.fixedTimestep) {
            // 执行逻辑更新
            this.fixedUpdate(this.fixedTimestep);
            
            // 减去固定步长
            this.accumulator -= this.fixedTimestep;
            
            // @if DEBUG
            this.statsManager?.recordLogicFrame();
            // @endif
            
            logicUpdateCount++;
            
            // 安全检查：防止无限循环
            if (logicUpdateCount > 10) {
                Log.ecs.error('逻辑更新次数过多，强制退出', { count: logicUpdateCount });
                this.accumulator = 0;
                break;
            }
        }
        
        // @if DEBUG
        // 开发环境：统计计算
        if (this.statsManager) {
            const logicEndTime = this.statsManager.getNow();
            const logicTime = logicEndTime - logicStartTime;
            
            if (logicUpdateCount > 0) {
                this.statsManager.recordLogicTime(logicTime);
            }
            
            const updateEndTime = this.statsManager.getNow();
            const renderTime = updateEndTime - updateStartTime - logicTime;
            
            this.statsManager.recordRenderTime(renderTime);
            this.statsManager.updateStats();
        }
        // @endif
        
        // 4. 计算插值因子（0-1）
        if (this.enableInterpolation) {
            this.interpolationAlpha = this.accumulator / this.fixedTimestep;
        } else {
            this.interpolationAlpha = 0;
        }
    }
    
    /**
     * 固定时间步长更新（逻辑系统）
     * @param fixedDeltaTime 固定的时间步长
     */
    private fixedUpdate(fixedDeltaTime: number): void {
        this.isInLogicUpdate = true;
        
        try {
            // 直接执行所有逻辑系统
            const systemCount = this.logicSystems.length;
            for (let i = 0; i < systemCount; i++) {
                const system = this.logicSystems[i] as any;
                // 调用系统的执行方法（execute0 是 ComblockSystem 的私有方法）
                if (typeof system.execute0 === 'function') {
                    system.execute0(fixedDeltaTime);
                }
            }
        } catch (error) {
            Log.ecs.error('逻辑更新出错', { error });
        } finally {
            this.isInLogicUpdate = false;
        }
    }
    
    /**
     * 获取插值因子（供渲染系统使用）
     * @returns 插值因子（0-1）
     */
    getInterpolationAlpha(): number {
        return this.interpolationAlpha;
    }
    
    /**
     * 获取固定时间步长
     */
    getFixedTimestep(): number {
        return this.fixedTimestep;
    }
    
    /**
     * 获取逻辑帧率
     */
    getLogicFPS(): number {
        return 1 / this.fixedTimestep;
    }
    
    /**
     * 是否正在执行逻辑更新
     */
    isExecutingLogicUpdate(): boolean {
        return this.isInLogicUpdate;
    }
    
    // @if DEBUG
    /**
     * 获取统计信息（仅开发环境）
     */
    getStats() {
        return this.statsManager?.getStats(
            this.fixedTimestep,
            this.accumulator,
            this.interpolationAlpha,
            this.enableInterpolation
        ) || null;
    }
    
    /**
     * 打印统计信息（仅开发环境）
     */
    printStats(): void {
        this.statsManager?.printStats(
            this.fixedTimestep,
            this.accumulator,
            this.interpolationAlpha,
            this.enableInterpolation
        );
    }
    
    /**
     * 重置统计信息（仅开发环境）
     */
    resetStats(): void {
        this.statsManager?.resetStats();
    }
    // @endif
    
    /**
     * 重置累加器（慎用，可能导致跳帧）
     */
    resetAccumulator(): void {
        this.accumulator = 0;
        Log.ecs.info('累加器已重置');
    }
    
    /**
     * 清空所有逻辑系统
     */
    clear(): void {
        this.logicSystems = [];
        this.accumulator = 0;
        this.interpolationAlpha = 0;
        
        // @if DEBUG
        this.resetStats();
        // @endif
        
        Log.ecs.info('FixedUpdateManager 已清空');
    }
}

/**
 * 使用说明：
 * 
 * FixedUpdateManager 是一个轻量级管理器，不继承 ECSRootSystem。
 * 它直接管理逻辑系统列表，避免创建多余的根系统实例。
 * 
 * 架构设计：
 * - WorldSystem（唯一的 ECSRootSystem）管理渲染系统（60 FPS）
 * - FixedUpdateManager（管理器）管理逻辑系统（20 FPS）
 * 
 * 通过 DI 容器获取实例：
 * ```typescript
 * import { container, ServiceIdentifiers } from '../../core/di';
 * const fixedUpdateManager = container.resolve<FixedUpdateManager>(ServiceIdentifiers.FixedUpdateManager);
 * const worldSystem = container.resolve<WorldSystem>(ServiceIdentifiers.WorldSystem);
 * 
 * // 注入依赖
 * worldSystem.setFixedUpdateManager(fixedUpdateManager);
 * 
 * // 注册逻辑系统（20 FPS）
 * fixedUpdateManager.registerLogicSystem(movementLogicSystem);
 * 
 * // 注册渲染系统（60 FPS）
 * worldSystem.add(renderSystem);
 * ```
 * 
 * 详细文档：
 * @see assets/scripts/ecs/ECS_ROOT_ARCHITECTURE.md
 */
